home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 001 / jmodem.arc / JMODEM.DOC < prev    next >
Encoding:
Text File  |  1988-09-13  |  12.9 KB  |  316 lines
  1.  
  2.  
  3.                                   J M O D E M
  4.                               File Transfer System
  5.                                  Compliments of
  6.                                Richard B. Johnson
  7.                                 PROGRAM EXCHANGE
  8.                                  (719) 548-0108
  9.                                September 13, 1988
  10.  
  11.           General:
  12.           First Let me get this over with.
  13.           MS-DOS is a registered trademark of Microsoft Corporation
  14.           IBM, IBM-PC, IBM-XT, AT, are registered trademarks of Inter-
  15.           national Business Machines, Inc. WILDCAT! is a trademark of
  16.           Mustang Software. XMODEM is a public-domain file-transfer
  17.           protocol developed by Ward Christensen.
  18.  
  19.           JMODEM is released into the public domain. As with most
  20.           public-domain protocols, you are advised that there is no
  21.           implied warranty of any kind. The source-code is provided so
  22.           that you may determine for yourself if this program may
  23.           serve a useful purpose. It is written in Microsoft MASM
  24.           Assembly-language using good standards of engineering prac-
  25.           tice. It does not use any strange or "undocumented" func-
  26.           tions of the MS-DOS operating system.
  27.  
  28.                 PLEASE UPLOAD THIS FILE (The ARC file) to as many
  29.                 BBS systems as you can so that it gets installed
  30.                 all around the country.
  31.  
  32.           Introduction:
  33.           JMODEM is a new file-transfer protocol developed to be used
  34.           as an "external protocol" on BBS systems and personal com-
  35.           puters using the IBM-PC/AT/XT structure and the MS-DOS oper-
  36.           ating system.
  37.  
  38.           This file-transfer system features:
  39.  
  40.                 o       16-bit CRC for verification
  41.                 o       File size is exactly maintained
  42.                 o       Data compression.
  43.                 o       Rapid host/remote synchronization.
  44.                 o       Variable-length transmission blocks which,
  45.                         if there are few errors, increase to 8192
  46.                         data-bytes in length.
  47.                 o       Flow control (automatic)
  48.                 o       Hangup protection
  49.                 o       Aborted files are saved
  50.                 o       Files being overwritten are renamed to
  51.                         ".OLD", rather than deleted.
  52.                 o       COM1 / COM2 support.
  53.                 o       Interrupt on received characters allows data
  54.                         to be received while the previous block is
  55.                         being written to disk. This provides almost
  56.                         continuous data transmission without long
  57.                         waits between blocks.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                      - 1 -
  64.           
  65.  
  66.           JMODEM is not for everyone! It does not have any pretty
  67.           screens to dazzle the user. It is designed to maximize the
  68.           amount of data that can be transferred in a given time (and
  69.           reduce telephone cost). It does this by sending very long
  70.           blocks of data and encoding (compressing) the data wherever
  71.           possible. Since long blocks of data are subject to many
  72.           transmission errors, a 16 bit CRC is used to determine the
  73.           data integrity. As many as ten retries are made if the data
  74.           is not correctly received. If you have a noisy telephone
  75.           circuit, you will find that JMODEM will abort more often
  76.           than the XMODEM protocol which sends very short blocks. A
  77.           future version that will be downward-compatible with the ex-
  78.           isting version is being developed that will do "heroic"
  79.           retries and will even go down to a 16-byte block-lengths if
  80.           that's what is necessary to get the data transferred.
  81.  
  82.           Once synchronization between the remote computer and the
  83.           host are established, JMODEM paints a status block on the
  84.           screen that shows how the file transfer is going. The status
  85.           screen shows the block being transmitted (or the last
  86.           received), the length of the block, and the total bytes hav-
  87.           ing been transmitted (or received). A special synch-
  88.           ronization routine is used so that the first block is not
  89.           thrown away as happens so often in XMODEM type routines.
  90.           During the synchronization routine, where the host is wait-
  91.           ing for the user to enter the proper file parameters (a 30
  92.           second wait).  You can abort immediately by sending a con-
  93.           trol X (^X). After actual file transfer begins, ie. when you
  94.           see the status window on the screen, no input from the key-
  95.           board is possible. You send a control BREAK to abort the
  96.           transmission (or ^C). In this case, the program will abort
  97.           after the block being sent/received is complete. This could
  98.           take 15 or more seconds with long blocks so be patient.
  99.  
  100.           In the event that carrier is lost (the user disconnected),
  101.           the file-transfer program will also abort. This, too, could
  102.           take as long as 15 seconds.
  103.  
  104.           How it works:
  105.           The block size starts out at 512 bytes (or the actual bytes
  106.           in the file -- whichever is less). To this is added a 6-byte
  107.           overhead. If the block transfer occurred without any
  108.           retries, the block length is increased by 512 bytes to 1024
  109.           bytes. As long as the transmission was successful without
  110.           incurring any re-tries, the block-length increases to a max-
  111.           imum of 8192 bytes. There is still the same 6-byte overhead
  112.           so the maximum block length will actually be 8198 bytes. Any
  113.           time there are retries, the block length (on the next new
  114.           string) is decreased by 512 bytes. The string-length is
  115.           never reduced to less than 512 bytes due to errors. When the
  116.           last bytes are read from the file, the block length may be
  117.           as little as 7 bytes (one data byte, plus the 6 byte over-
  118.           head). The file size as received will be exactly the file
  119.           size as transmitted. XMODEM will "round-up" the file size to
  120.           the next higher block. This means that MS-DOS's COMP (com-
  121.  
  122.  
  123.  
  124.  
  125.  
  126.                                      - 2 -
  127.           
  128.           pare) will always fail when you attempt to check files that
  129.           have been sent by XMODEM and many other protocols.
  130.  
  131.           When the file is read, an attempt is made to compress the
  132.           data using the well-known RLL process where multiple bytes
  133.           are compressed into a 4-byte statement.
  134.  
  135.           For instance a string that looks like this (hex):
  136.                 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0
  137.           Gets compressed into this:
  138.                 BB 0F 00 A0
  139.                  |  |  |  |__________ Byte to repeat
  140.                  |  |  |_____________ High byte of repeat length
  141.                  |  |________________ Low byte of repeat length
  142.                  |___________________ Sentinel Byte
  143.  
  144.           The sentinel-byte (BBH), when encountered in a data stream
  145.           will get expanded to four bytes. Therefore, it is possible
  146.           for the "compressed" data string to actually be longer than
  147.           the original. If this occurs, the original string is sent
  148.           rather than the longer encoded one. Since the kind of data
  149.           sent can be different from block-to-block, it is necessary
  150.           to send a control-byte along with the data so the receiver
  151.           had determine how to operate on the data.
  152.  
  153.           This is the control structure:
  154.  
  155.           00 02 00 0B 01 02 03 04 05 06 07 08 09 0A .... 0A EA
  156.            |  |  |  |  |                                 |  |_ CRC
  157.            |  |  |  |  |                                 |____ CRC
  158.            |  |  |  |  |______________________________________ data
  159.            |  |  |  |_________________________________________ rec.
  160.            |  |  |____________________________________________ control
  161.            |  |_______________________________________________ length
  162.            |__________________________________________________ Length
  163.  
  164.           Two bytes are used for the string length and two bytes are
  165.           used for the CRC. As is standard in memory, the high-byte
  166.           looks "to people using DEBUG" swapped with the low byte. The
  167.           data is transmitted exactly as the memory image.
  168.  
  169.           The length (a word) begins the string so the receiver may
  170.           know exactly how may bytes to receive.
  171.  
  172.           The control byte is bit-mapped to 8 possibilities. The ones
  173.           most important are:
  174.  
  175.                         NORMAL DATA
  176.                         COMPRESSED DATA
  177.                         END OF FILE
  178.                         ABORT
  179.  
  180.           This is now the receiver "knows" what to do with the data.
  181.  
  182.           The CRC is generated using this polynomial:
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.                                      - 3 -
  190.           
  191.           X =  X + X^(2(n-mod 7).......  Where n = t(n-1)
  192.                                          And t = string length
  193.  
  194.           It has the advantage of simplicity in assembly-language pro-
  195.           gramming and will detect errors with a probability of about
  196.           one undetected error in 2^132 (which is a very large num-
  197.           ber). It does not correct errors so its not important to use
  198.           some "standard" function to generate the CRC.
  199.  
  200.           Usage:
  201.           This program uses parameters on the command line.
  202.  
  203.           JMODEM S <filename.typ>       ( Sends a file to COM1:)
  204.           JMODEM R <filename.typ>       ( Receives a file from COM1:)
  205.           JMODEM S1 <filename.typ>      ( Sends a file to COM1:)
  206.           JMODEM R1 <filename.typ>      ( Receives a file from COM1:)
  207.           JMODEM S2 <filename.typ>      ( Sends a file to COM2:)
  208.           JMODEM R2 <filename.typ>      ( Receives a file from COM2:)
  209.  
  210.           Support for COM3 and COM4 have been added on revision level
  211.           V1.05 . Note that the standards for port locations are de-
  212.           facto standards only and may not be the ports actually used
  213.           in your computer. Please modify the communications port
  214.           structures at the beginning of the assembly-language program
  215.           to match your system parameters if they are different. The
  216.           modifications should be done to the STRUCTURES, not to the
  217.           EQUATES!
  218.  
  219.  
  220.           In a batch file, <filename.typ> may be a substitution
  221.           character.
  222.           JMODEM S2 %1                  ( Sends a file to COM2:)
  223.           JMODEM R2 %1                  ( Receives a file from COM2:)
  224.  
  225.           How to set up batch files to use this program:
  226.           If you are using PCPLUS (PROCOMM +), the batch files should
  227.           be set up like this:
  228.  
  229.           (JDOWN.BAT)
  230.           JMODEM R1 %1                  ( Download from COM1:)
  231.  
  232.           (JUP.BAT)
  233.           JMODEM S1 %1                  ( Upload to COM1:)
  234.  
  235.           If you are running a WILDCAT! bulletin board, the external
  236.           protocol files should be set up like this:
  237.  
  238.           (JUP.BAT)
  239.           CD D:\WILDCAT\PROTOCOL
  240.           IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
  241.           JMODEM R1 %3
  242.           IF ERRORLEVEL 1 GOTO END
  243.           COPY %3 %4
  244.           :END
  245.           DEL %3
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.                                      - 4 -
  253.           
  254.           (JDOWN.BAT)
  255.           CD D:\WILDCAT\PROTOCOL
  256.           IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
  257.           JMODEM S1 %3
  258.           IF ERRORLEVEL 1 GOTO BAD
  259.           GOTO END
  260.           :BAD
  261.           COPY ALL.OK TRANSFER.BAD
  262.           :END
  263.  
  264.           JMODEM does not require any information about handshaking.
  265.           It will look at the modem port and figure out for itself
  266.           what to do.
  267.  
  268.           In the event that the modem carrier is lost, JMODEM will
  269.           abort. Since JMODEM only checks the modem port occasionally,
  270.           it may take several seconds to abort when the carrier is
  271.           lost. It is impossible for a user to get at the DOS level
  272.           through JMODEM. Do NOT use the CTTY command in the external
  273.           protocol batch files. JMODEM returns ERRORLEVEL 1 if there
  274.           was any error in transmission or reception. It returns ER-
  275.           RORLEVEL 0 (no error) otherwise. It does not delete files
  276.           that have been partially received although it properly
  277.           closes them. The system operator can arrange the batch files
  278.           to delete them if required.
  279.  
  280.           When JMODEM attempts to create a file that already exists it
  281.           can't ask the user if the old one should be deleted since
  282.           the user is probably not in a terminal program at the time.
  283.           Therefore, JMODEM renames the other file to <filename.OLD>
  284.           and creates the new file.
  285.  
  286.           - Finis -
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.                                      - 5 -
  316.           
  317.  
  318.